This document here because the documentation for MacGambit toolbox calls was not always complete, in the sense that the arguments required by some functions were not always obvious. The toolbox calls are VERY unforgiving - supplying a bogus value (say, #f, instead of a window id to mac#setport) is a very quick way to exit your application. Good example code is provided for some of the toolbox calls in the reference directory and in the samples directory. Here is some additional documentation:
Terms:
window id - an integer value returned by a call to mac#newwindow, mac#frontwindow, etc. which is the window id or pointer to the window entity
mac#point - a structure consisting of a vertical screen coordinate v and a horizontal screen coordinate h
mac#rect - a structure consisting of top, bottom, left, and right screen coordinates
port - usually a window id returned from (i.e.) mac#newwindow
Toolbox Functions:
(Note: if functions are not useful, or usage has not been determined, the function name is not in special font)
Windows:
(mac#newwindow bounds title visible procid behind goaway)
bounds - a mac#rect structure (mac#rect top bottom left right)
title - a string for the window title
visible - #t or #f, controlling whether the window is shown
procid - actually the window type as given in Macintosh Toolbox essentials, Ch 4 Window Manager
0 - movable,sizable, window, no zoom box
1 - alert box or modal dialog box
2 - plain box
3 - plain box with shadow
4 - movable window, no size box or zoom box
5 - movable modal dialog box
8 - standard document window
12 - zoomable, resizable window
16 - rounded-corner window
behind - controls what window(s) the new window is behind
-1 - none (put in front)
0 - all (put in back)
winid - where winid is window id of the window that the new window is to be put behind
goaway - #t or #f, controls whether the window has a goaway box
It should be noted that merely providing a goaway box or making the window movable, zoomable or resizable will not automatically confer these capabilities on the window. For hints about what code to use to do this, see the examples in ???
(mac#getnewwindow windowid behind)
windowid - a resource ID of new window (must have been added to the MacGambit world using ResEdit
behind - -1, 0, or winid as in newwindow, above
(mac#disposewindow w) - kills the window pointed to by w (note: trying to do anything with w after this call will kill you dead)
w - window id
(mac#selectwindow w) - selects the window (brings it to front)
w - window id
(mac#hidewindow w) - hides the window (makes it invisible)
w - window id
(mac#showwindow w) - makes the window visible but does not otherwise affect it: the window may be underneath other windows and will not accept input until selected
w - window id
(mac#frontwindow) - returns the window id of frontmost window
(mac#findwindow pt w-cell) - puts the window id of the frontmost window that contains the point pt in the car of w-cell
pt - a mac#point structure (see mac#point call, below)
w-cell - a list of at least two members, the car of which is the destination for the window id
(mac#trackgoaway w pt) - used to return whether the mouse was clicked and released in the goaway box of the window with window id w
w - window id of window where goaway box was clicked
pt - a mac#point structure
(mac#dragwindow w pt r) - allows a window to be dragged by the title bar within a rectangle r when clicked on the title bar at point pt
w - window id
pt - a mac#point structure
r - a mac#rect structure
(mac#invalrect port r) - invalidates a rectangular region r in a port
port - window id
r - mac#rect structure
(mac#beginupdate w) - begins update process
w - window id
(mac#endupdate w) - ends update process
w - window id
Quickdraw
(mac#point v h) - creates a pt structure at v, h
v - vertical window coordinate
h - horizontal window coordinate
(mac#point-v r) - gets vertical coordinate from r
r - a mac#point structure
(mac#point-h r) - gets horiz coord from r
r - a mac#point structure
(mac#point-v-set! r x) - sets horiz coord of r
r - a mac#point structure
x - a screen coordinate (integer)
(mac#point-h-set! r x) - sets vertical coord of r
r - a mac#point structure
x - a screen coordinate (integer)
(mac#rect top left bottom right) - creates a mac#rect structure
(mac#rect-top r) - returns the top screen coord of r
r - a mac#rect structure
(mac#rect-left r) - returns the left screen coord of r
r - a mac#rect structure
(mac#rect-bottom r) - returns the bottom screen coord of r
r - a mac#rect structure
(mac#rect-right r) - returns the right screen coord of r
r - a mac#rect structure
(mac#rect-top-set! r x) - sets the top screen coord of r to x
r - a mac#rect structure
x - a screen coordinate (integer)
(mac#rect-left-set! r x) - sets the top screen coord of r to x
r - a mac#rect structure
x - a screen coordinate (integer)
(mac#rect-bottom-set! r x) - sets the top screen coord of r to x
r - a mac#rect structure
x - a screen coordinate (integer)
(mac#rect-right-set! r x) - sets the top screen coord of r to x
r - a mac#rect structure
x - a screen coordinate (integer)
(mac#openport port) - not really needed
(mac#initport port) - ditto
(mac#closeport port) - ditto
(mac#setport port) - sets the output port for Quickdraw to the specified port
port - a graphics port (typically a window id)
(mac#getport) - returns the currently active QD port
(mac#setorigin port h v)
(mac#backpat port pat) - sets the background pattern of the graphics port to the supplied pattern
port - a graphics port (typically a window id)
pat - a string of length of length 4 works here - the characters determine the pattern
(mac#hidecursor) - make cursor invisible
(mac#showcursor) - make cursor visible
(mac#pensize port width height) - sets the pen width and height
port - a graphics port (typically a window id)
width - desired pen width in pixels (integer)
height - desired pen height in pixels (integer)
(mac#penmode port mode) - sets the pen mode which controls how a graphic operation (say, drawing a line) affects the pixels being drawn.
(mac#penpat port pat) - sets the foreground pen pattern
port - a graphics port (typically a window id)
pat - a pattern (string of length 4) of bits
(mac#pennormal port) - returns the pen to default settings
port - a graphics port (typically a window id)
(mac#moveto port h v) - moves the graphics pen to h,v
port - a graphics port (typically a window id)
h - a horizontal window coordinate (integer)
v - a vertical window coordinate (integer)
(mac#move port dh dv) - moves the graphics pen by dh,dv
port - a graphics port (typically a window id)
dh - a horizontal displacement (integer)
dv - a vertical displacement (integer)
(mac#lineto port h v) - draws a line from current pt to h,v
port - a graphics port (typically a window id)
h - a horizontal window coordinate (integer)
v - a vertical window coordinate (integer)
(mac#line port dh dv) - draws a line from current pt along dh,dv
port - a graphics port (typically a window id)
dh - a horizontal displacement (integer)
dv - a vertical displacement (integer)
(mac#textfont port font) - sets the port text to specified font
port - a graphics port (typically a window id)
font - a string, such as "chicago"
(mac#textmode port mode) - sets the port text to mode
port - a graphics port (typically a window id)
mode - (see mac#penmode, above)
(mac#textsize port size) - set port text size
port - a graphics port (typically a window id)
mode - (see mac#penmode, above)
(mac#spaceextra port extra)
(mac#drawchar port ch) - draws a character ch on the port at the current graphics pen location
port - a graphics port (typically a window id)
ch - a character
(mac#drawstring port s) - draws a string s on the port at the current graphics pen location
port - a graphics port (typically a window id)
s - a string
(mac#drawtext port textbuf firstbyte bytecount)
port - a graphics port (typically a window id)
textbuf - a string
(mac#charwidth port ch) - returns the width of ch in pixels in the current font on the port
port - a graphics port (typically a window id)
ch - a character
(mac#stringwidth port s) - returns the width of s in pixels
port - a graphics port (typically a window id)
s - a string
(mac#textwidth port textbuf firstbyte bytecount)
(mac#localtoglobal port pt) - convert window coords in window port of pt to screen coords
port - a graphics port (typically a window id)
pt - a mac#point
(mac#globaltolocal port pt) - convert screen coords of pt to window coords in the window port
port - a graphics port (typically a window id)
pt - a mac#point
(mac#framerect port r) - draw a rectangle (outline)
port - a graphics port (typically a window id)
r - a mac#rect
(mac#paintrect port r) - draw a rectangle (filled)
port - a graphics port (typically a window id)
r - a mac#rect
(mac#eraserect port r) - erase a rectangle
port - a graphics port (typically a window id)
r - a mac#rect
(mac#invertrect port r) - invert the pixels of a rectangle
port - a graphics port (typically a window id)
r - a mac#rect
(mac#fillrect port r pat) - fill a rectangle with a pattern
port - a graphics port (typically a window id)
r - a mac#rect
pat - a pattern (string of length 4)
(mac#frameroundrect port r ovwd ovht)
port - a graphics port (typically a window id)
r - a mac#rect
ovwd - edge-rounding oval width
ovht - edge-rounding oval height
(mac#paintroundrect port r ovwd ovht)
port - a graphics port (typically a window id)
r - a mac#rect
ovwd - edge-rounding oval width
ovht - edge-rounding oval height
(mac#eraseroundrect port r ovwd ovht)
port - a graphics port (typically a window id)
r - a mac#rect
ovwd - edge-rounding oval width
ovht - edge-rounding oval height
(mac#invertroundrect port r ovwd ovht)
port - a graphics port (typically a window id)
r - a mac#rect
ovwd - edge-rounding oval width
ovht - edge-rounding oval height
(mac#fillroundrect port r ovwd ovht pat)
port - a graphics port (typically a window id)
r - a mac#rect
ovwd - edge-rounding oval width
ovht - edge-rounding oval height
pat - a pattern (string of length 4)
(mac#frameoval port r)
port - a graphics port (typically a window id)
r - a mac#rect
(mac#paintoval port r)
port - a graphics port (typically a window id)
r - a mac#rect
(mac#eraseoval port r)
port - a graphics port (typically a window id)
r - a mac#rect
(mac#invertoval port r)
port - a graphics port (typically a window id)
r - a mac#rect
(mac#filloval port r)
port - a graphics port (typically a window id)
r - a mac#rect
(mac#framearc port r startangle arcangle)
(mac#paintarc port r startangle arcangle)
(mac#erasearc port r startangle arcangle)
(mac#invertarc port r startangle arcangle)
(mac#fillarc port r startangle arcangle pat)
Menus (see examples in Utilities.scm)
(mac#newmenu menuid str)
(mac#getmenu resourceid)
(mac#disposemenu themenu)
(mac#appendmenu themenu str)
(mac#addresmenu themenu thetype)
(mac#insertresmenu themenu thetype)
(mac#insertmenu themenu beforeid)
(mac#drawmenubar)
(mac#deletemenu menuid)
(mac#clearmenubar)
(mac#getnewmbar menubarid)
(mac#setmenubar menulist)
(mac#menuselect p)
(mac#menukey ch)
(mac#hilitemenu menuid)
(mac#disableitem themenu item)
(mac#enableitem themenu item)
(mac#getmhandle menuid)
Events
(mac#event-what event)
(mac#event-message event)
(mac#event-when event)
(mac#event-where event)
(mac#modifiers event)
(mac#modifiers-button? modifiers)
(mac#modifiers-command? modifiers)
(mac#modifiers-shift? modifiers)
(mac#modifiers-alphalock? modifiers)
(mac#modifiers-option? modifiers)
Standard file get/put
(mac#sfgetfile [prompt] [filetype]) - pops up standard input file dialog box, and if filetype is supplied, shows only files of that type, otherwise "TEXT"; returns a filename
[prompt] - only required if filetype is to be supplied - ignored
[filetype] - (optional) four-character type ("TEXT", "PICT", etc.) - more 4-character strings may be appended for additional types, such as creator ("gamO", etc.)
(mac#sfputfile [prompt] [filename]) - pops up a standard output file dialog box, with prompt above file name entry box, and filename in file entry box, if supplied
[prompt] - (optional) prompt above file box - a string
[filename] - (optional) default filename - a string
Misc
(mac#getmouse pt) - returns the current location of the mouse in the location pt in window coords (pt must have been set to a mac#point structure before calling)
(mac#button) - returns #t if mouse button has been pressed, otherwise #f
(mac#tickcount) - returns an integer which is the total time the computer has been running at the time of the call, in 1/60's of a second
(mac#delay duration) - delays operation for duration
duration - time in 1/60's of a second
(mac#sysbeep duration) - invoke error beep for duration
